The Use Case

Whenever developing a plug-in for Eclipse or building a RCP application or Equinox-based product with PDE+Tycho, there will be the need to include a third-party dependency which is currently not part of your target.

In some cases, one can simply head over to Eclipse Orbit, but there are two major drawbacks in this regard – especially in prototyping scenarios:

• Eclipse Orbit is dedicated to Eclipse projects. Thus, if there is no demand from any Eclipse project, it is hard to get content in and it takes a considerable time to appear there
• Even if the required package is there, it might be incomplete or outdated. At the time of this writing, there are 12 outstanding update requests whereby the oldest one dates back to 2017 as well as numerous issues for fixing inappropriate repacking dating back to 2009

Another option is to download the artifact and put it into the target platform with a directory target entry which is possible thanks to the support we added recently in Tycho for local target locations. This works quite well if you’d like to try things out quickly and the artifact in question is already an OSGi bundle, but becomes undesirable when it comes to version control, non-OSGI artifacts and long-term maintenance.

Some of the above could be solved by a feature of Tycho which uses Maven dependencies as a target platform. This was also recently enhanced by us to even generate basic meta-data for non-OSGi artifacts. This works well with Maven builds, but fails to give a good user experience in the IDE, e.g. PDE fails to identify the packages provided from the Maven artifacts.

Considerable effort has now been taken by us to solve the use case in a smoother manner – both from the developer’s and the build-time points of view – by reworking a proof-of-concept dating back to 2017. This POC has built upon a rather unknown feature in Eclipse PDE that enables custom target definitions.

The Solution

M2Eclipse already provides tight integration for Apache Maven into the IDE. Thus, it was decided to place the new feature there. The new feature is currently not part of the standard EPP installations. Therefore, the first step is to install it from the m2e update site, go to Help > Install new software and enter the https://download.eclipse.org/technology/m2e/releases/latest/ repository there. Then install the latest version of the m2e feature (at least 1.17.0 is required).

After that, create a new target (or open a new one if you already have one), hit the Add button and you will see a new type of “Maven” to add

Hitting Next, you will be presented with a dialog where you can enter the desired Maven coordinate. If you copy a usual dependency XML fragment from Maven Central, for example, the content of the clipboard will automatically be copied into the fields.

Copy the following snippet just before starting to add a Maven location:

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcpkix-jdk15on</artifactId>
    <version>1.67</version>
</dependency>

Besides the obvious Maven settings, there are two that might need some more extensive explanations: Missing OSGi Manifest and Dependencies Scope.

The Dependencies Scope simply manages the process if you want to include dependent artifacts or only the master artifact itself. Just keep in mind that this is a pure Maven issue and does not take OSGi meta-data into account. If it is not declared in maven pom as a (transitive) dependency, it won’t be included!

Missing OSGi Manifest comes into play if the artifact (or its dependencies) are not already bundles and can take one of three values:

1. Ignore If any dependency is not already an OSGi bundle, it is simply ignored and will not be included in the target platform. This is useful if you only want to include as much as possible
2. Error If any dependency is not already an OSGi bundle, you will get an error and the target can’t be resolved. That is useful if you want to include either all or nothing.
3. Generate is the most powerful option and enables the usage of even non-OSGi artifacts. Whenever such an artifact is encountered, a manifest is generated for this. You can even edit the instructions that are used to generate the manifest, e.g. if you prefer a different naming scheme or require special import/export considerations.

Another useful option is the Include Artifact Source. If it is checked, the sources will be downloaded (if available) for all artifacts and automatically transformed in a way which PDE can understand.

After that, your artifact is added to the target and ready to be used!

By default, you will be presented with a tree showing the Maven artifacts referenced. You can tick the Show Location Content option in order to see what actual bundles result from your selection. As in our example, if everything is already an OSGi bundle, you won’t notice anything special.

Let’s add another artifact that actually will have a non-OSGi dependency. You can once again simply copy the following snippet in order to avoid typing it again.

<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity</artifactId>
<version>1.7</version>
</dependency>

If you add this to your target and tick the Show Location Content option, you will see that the oro:oro dependency has a special icon. That means that it was automatically wrapped as an OSGi bundle. By default, the group id, artifact id and a prefix (wrapped) are used in order to generate a name out of the Maven coordinate and the Maven version is used for the bundle (and its package exports).

You probably also want to try out the different outcomes if you choose another missing manifest strategy (e.g. ignore/error) before proceeding.

As described before, if you are not happy with the defaults, you can change them. Just hit the Edit button and click on the Edit Instructions link.

Under the hood, BND is used to analyze the artifact and create the appropriate OSGi header. Therefore, if you are already familiar with BND, you will already recognize what’s going on. If not, don’t focus on basic adjustments because it is not a big deal and you will soon become more used to it. There is documentation on the BND site (either click on the link to open a browser or hit the Help button to get it online) and a lot of web resources describing its usage.

Just for demonstration purposes, uncheck Use Default and you could, for example, change the prefix used to generate the bundle symbolic name with a custom vendor prefix, then confirm the edit and you are done!

That’s it for the UI part. Now head over to how to use this with Tycho. Actually, that part is not that special and if you already using a target file for your project and you’re all set. If not, you will need to set up your created target to be used by Tycho as described here for using the same things in Tycho and your IDE.  There is no need for additional configurations, no need for defining the dependencies from the target in the pom (and if you are using it pomless, not even for a pom)!

This feature is only available from Tycho 2.2.x on, make sure to use a recent Tycho version!

There is just one thing left to consider regarding the include source option. You can tell Tycho to either respect the flag from the target, ignore sources or even to always include them regardless of the settings. You can read more about it here.

Current Limitations

• Instructions can currently only be edited on the top level. If you need special treatment of dependencies, the only choice at the moment is to add them separately. This is owing to a limitation in the PDE Editor Model. We are currently working on a solution for this, this will be included in the next Eclipse release.
• Features are currently not supported even though it is possible to deploy them as Maven artifacts
• You can’t add a “pom” type artifact and use its dependencies. It would be possible to map out the pom type into an automatically-generated feature including its dependencies as bundles
• Currently, it is neither possible to preview the outcome of the manifest generation nor review the generated manifest afterwards
• Each artifact is currently analyzed separately by BND
• Due to Bug 570883 care must be taken when using snapshot, see the bug for more details

There might be more to discover. Let us know if you think there would be more things to add. If you feel that there is a missing feature (or bug you have discovered) which are crucial to your mission, consider the following:

1. Let us know by opening a bug report for Tycho or Maven2Eclipse
2. Provide a patch that fixes the problem. It’s all open source and everyone is encouraged to participate!
3. You can always contact us and offer funding for a feature or bug fix